Review: PR #65 — reference/subnet-types.md

Must fix

• Fiduciary subnet node count is unverified / sources conflict: The page states the fiduciary subnet (pzp6e) has 34 nodes. The icp-cli docs (.sources/icp-cli/docs/guides/deploying-to-specific-subnets.md) and the portal's deploy-specific-subnet.mdx both say 34 nodes, but the portal's references/subnets/subnet-types.mdx says 31 nodes. Because these sources conflict, the page should direct readers to the ICP Dashboard for the authoritative current count, or a human reviewer should verify against the live dashboard before merging. If 34 is correct, the cost formula table (1,307,692,307,692 cycles for fiduciary creation = 500B × 34/13) is internally consistent — but so would 31 nodes yield a different figure.

• Fiduciary subnet full principal — potential discrepancy: The page uses pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae. The icp-cli docs use the same string. However, the portal's subnet-types.mdx links to pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeq5-fk5o7-yae (different suffix: vpeq5-fk5o7-yae vs vpeez-fez7a-iae). One of these is wrong. The ICP Dashboard link in the portal uses the vpeq5-fk5o7-yae form. A human reviewer must verify the correct full principal against the live ICP Dashboard before merging.

Suggestions

• Canister creation USD cost: The page states ~$0.68 USD for canister creation (May 2025). The portal gas-cost page states ~$0.65 USD. Both say "approximately," so these are rounding differences rather than errors, but the dates differ too (May 2025 vs whatever the portal reflects). Consider noting that prices fluctuate with ICP/XDR exchange rates and linking to the Cycles costs page for current figures rather than embedding a specific USD value here.

• System subnet uzr34 label "Application services": The informal label "Application services" for the uzr34 subnet is not used in any of the source material. The portal calls it the system subnet hosting Internet Identity, cycles ledger, exchange rate canister, and dashboard. This label may confuse readers who wonder why an "application services" subnet is in the "System subnets" section. Consider using "Infrastructure services" or just dropping the informal names and using only the principal prefix.

• "subnets share a 2 TiB storage budget": The page says "subnets share a 2 TiB storage budget" in the Application subnets section. This phrasing is ambiguous — it could read as all subnets sharing one 2 TiB pool. The intent is that each application subnet has a 2 TiB capacity (confirmed by .sources/portal/docs/building-apps/canister-management/resource-limits.mdx). Suggest rewording to "each application subnet has a 2 TiB storage capacity."

• Cycle cost formula section is duplicative: The "Cycle costs by subnet type" section (lines 113–130) repeats information already in the "Subnet properties explained" table (cycle cost multiplier formula) and the fiduciary section (cost example). Since this is a reference page and the full cost tables live at cycles-costs.md, consider removing or consolidating this section to avoid staleness. The embedded USD prices will require updates as exchange rates change.

• "ICP Dashboard" external URL policy: The page links to https://dashboard.internetcomputer.org multiple times. Per CLAUDE.md, prefer internal pages over external URLs when an internal page exists. There is no internal dashboard page in this repo, so these external links are acceptable. However, confirm that the dashboard URL (and not the old dashboard.ic0.app) is the current canonical URL before merging.

Verified

• All internal links resolve to actual files: ../guides/canister-management/subnet-selection.md, cycles-costs.md, and system-canisters.md all exist on this branch.
• No dfx references found.
• No mo:base imports found (no code examples use Motoko).
• No banned docs.internetcomputer.org or internetcomputer.org/docs/ URLs found.
• CLI commands (icp deploy -e ic --subnet <ID>) verified against .sources/icp-cli/docs/reference/cli.md: icp deploy, -e/--environment, and --subnet flags all exist and match the documented syntax.
• Frontmatter is complete: title, description, and sidebar.order are present and consistent with the page content.
• <!-- Upstream: --> comment is present at the end of the file.
• Page is .md (not .mdx) — correct, as there are no interactive components.
• European subnet principal bkfrj-6k62g-dycql-7h53p-atvkj-zg4to-gaogh-netha-ptybj-ntsgw-rqe confirmed against .sources/portal/docs/building-apps/developing-canisters/deploy-specific-subnet.mdx.
• System subnet principal prefixes (tdb26, uzr34, w4rem) and their canister assignments verified against portal source.
• 2 TiB per-subnet storage capacity confirmed by .sources/portal/docs/building-apps/canister-management/resource-limits.mdx.
• The four subnet types (Application, System, Fiduciary, European) and their general properties are consistent with both portal source files consulted.
• Page structure follows reference Diataxis type: property tables, factual descriptions, no tutorial steps. Appropriate for a reference page.
• Reader test: opening paragraph delivers immediately on the title ("Subnet Types Reference") — explains what a subnet is and what differentiates them. Strong opening.
• Next steps section present with appropriate links.

Review: Subnet Types Reference

Must fix

• Fiduciary subnet node count is disputed across sources: The page states 34 nodes, and the portal's deploy-specific-subnet.mdx also says 34 nodes, but portal's references/subnets/subnet-types.mdx says 31 nodes. The icp-cli source (deploying-to-specific-subnets.md) does not specify a node count — it only lists the principal ID. The cycle cost multiplier and the "Cost example" in the page are both calculated from 34 nodes (34/13 ≈ 2.6×). If the actual current count is 31 nodes, the cost example and multiplier would be wrong. This needs human verification against the live ICP Dashboard before merging. The Summary table entry (34 | ~2.6×) and the "Cost example" section would both need updating if the node count has changed.

• Content Brief gap — Bitcoin subnet and Internet Identity subnet not listed separately: The stub's Content Brief requests listing "Bitcoin subnet, Internet Identity subnet" as distinct items. The page addresses them briefly under "System subnets" (as the w4rem Bitcoin integration subnet and the uzr34 "Application services" subnet), but does not describe them as named subnet types with their own sections or entries in the summary table. A developer scanning this page would not find "Bitcoin subnet" or "Internet Identity subnet" as first-class entries. The brief intended these as identifiable items — at minimum, the summary table should clarify what each system subnet is named/known as (rather than only showing "System | Varies").

Suggestions

• "Application services" is not a recognizable label for uzr34: The page labels the uzr34 subnet as "Application services" in the system subnets table. Neither the portal's deploy-specific-subnet.mdx nor subnet-types.mdx uses this label — they describe uzr34 by its contents (Internet Identity, cycles ledger, exchange rate canister, ICP dashboard). The label is not wrong per se, but a developer looking for the "Internet Identity subnet" would not find it by scanning this table. Consider using "Internet Identity / services" or listing the key canisters inline.

• Summary table "System | Varies" is not useful for a reference page: The Summary table lists "System | Varies | N/A" for node count and cost. While technically accurate (system subnets can differ), a reference page that says "varies" for a known set of subnets adds little value. The three system subnets are enumerated in the section above — at least a footnote or parenthetical showing the known counts (e.g., NNS: varies, uzr34: 28) would improve utility. The portal's subnet-types.mdx specifies 28 nodes for uzr34 specifically.

• No --next-to flag mentioned: The icp-cli source (deploying-to-specific-subnets.md) mentions that if you have an existing canister on mainnet, you can deploy a new canister to the same subnet using --next-to <canister-id>. This is a useful colocation pattern that is described under "Colocation" in the page (line 36) but the CLI flag is not mentioned. The page would be more actionable if this flag were included.

• "Xnet" capitalization: Line 32 uses "Xnet" and line 37 uses "Xnet call overhead". The portal source uses "cross-subnet" — "Xnet" is the internal ICP term but may be unfamiliar to new developers. Consider spelling out "cross-subnet (Xnet)" on first use.

• USD price note caveat: The table on line 124–128 labels costs as "~USD (May 2025)". Given the volatility of ICP/USD, this annotation is appropriate. However, the table only shows canister creation — this creates a potential misimpression that these are the only costs. The text already links to cycles-costs.md for full tables, so this is minor.

Verified

• All internal links resolve: ../guides/canister-management/subnet-selection.md, cycles-costs.md, system-canisters.md — all confirmed present via ls.
• No banned patterns: no dfx references, no mo:base, no internetcomputer.org/docs/ links, no .mdx file created.
• CLI command syntax verified against .sources/icp-cli/docs/reference/cli.md and .sources/icp-cli/docs/guides/deploying-to-specific-subnets.md: icp deploy -e ic --subnet <principal> is correct. The --subnet flag exists in both icp deploy and icp canister create.
• Fiduciary subnet principal ID pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae matches the icp-cli source (.sources/icp-cli/docs/guides/deploying-to-specific-subnets.md line 41). Note: portal source uses a different suffix (vpeq5-fk5o7-yae) — the icp-cli version is more authoritative for the current CLI docs.
• European subnet principal bkfrj-6k62g-dycql-7h53p-atvkj-zg4to-gaogh-netha-ptybj-ntsgw-rqe matches portal source (deploy-specific-subnet.mdx line 72).
• System subnet principal prefixes (tdb26, uzr34, w4rem) and their content descriptions all match portal source (deploy-specific-subnet.mdx lines 54–58).
• Canister creation cost of 500B cycles confirmed against portal gas-cost page (gas-cost.mdx line 60: "500B cycles").
• 2 TiB subnet storage capacity confirmed against portal gas-cost page (gas-cost.mdx line 124).
• Cycle cost formula (cost = base × n / 13) is consistent with portal description: "The cycle costs scale linearly to the number of nodes."
• Upstream comment present and correctly formatted, listing both source files.
• Frontmatter complete: title, description, sidebar order — all present and consistent with page content.
• No dfx commands used anywhere in the page (correct — all CLI examples use icp deploy).
• Page is .md (not .mdx) — correct per project convention.

<!-- feedback-addressed -->

Feedback addressed — PR #65 (docs/reference/subnet-types.md)

Changes applied

Must-fix items:

1. Fiduciary subnet node count conflict (both reviews) — Sources conflict: portal/docs/references/subnets/subnet-types.mdx says 31 nodes, portal/docs/building-apps/developing-canisters/deploy-specific-subnet.mdx says 34 nodes, and the icp-cli source does not specify a count. Resolved by removing all hardcoded node counts for the fiduciary subnet and directing readers to the ICP Dashboard for the authoritative current value. The properties table, summary table, cost formula, and cost example table are all updated to use the dashboard reference or note the count-dependent formula. A verification note is added to the deploy command block as well.

2. Fiduciary principal ID ambiguity (both reviews) — The page uses the icp-cli-sourced principal (vpeez-fez7a-iae suffix), which differs from both portal source files (vpeq5-fk5o7-yae suffix). The icp-cli principal is kept (it is the most authoritative source for CLI documentation), but a note is added instructing readers to verify the full principal ID on the ICP Dashboard before deploying.

3. System subnet uzr34 label "Application services" (both reviews) — Label not used in any source material. Updated to "Internet Identity / infrastructure" to match the portal description and help developers find the subnet by its most recognizable tenant.

4. Content brief gap — system subnet names not prominent (review 2) — The system subnets table now uses descriptive names ("Internet Identity / infrastructure", "Bitcoin integration") so developers scanning for known subnets can identify them.

5. Ambiguous "subnets share a 2 TiB storage budget" (review 1) — Reworded to "each application subnet has a 2 TiB storage capacity" to make clear this is a per-subnet limit, not a shared pool.

Suggestion items applied:

6. Summary table system subnet row (review 2) — Updated from "Varies" to include the known uzr34 node count (28, per portal/docs/references/subnets/subnet-types.mdx) and indicate which subnets vary. Fiduciary row updated to reference dashboard.

7. USD price caveat (reviews 1 and 2) — Added a note that USD values are approximate and vary with the ICP/XDR exchange rate, with a link to Cycles costs for current figures.

8. Cycle cost formula section — hardcoded 34-node example — Updated the formula section to describe the multiplier as dependent on current node count, with 34 nodes as an example only.

9. Cycle cost multiplier formula in "Subnet properties explained" table — Generalized from the hardcoded 34-node example to the generic n/13 formula.

Items skipped

1. --next-to flag suggestion (review 2) — The reviewer noted that --next-to is mentioned in the portal source (deploy-specific-subnet.mdx) and could be added to the colocation section. Skipped: --next-to appears only as dfx deploy --next-to in the portal source. The dfx command is deprecated and banned per CLAUDE.md. There is no --next-to flag in the icp-cli source (verified: grep -r "next-to" .sources/icp-cli/ returns no results). Cannot add a flag that does not exist in the authorized CLI.

2. Fiduciary cycle cost row — specific cycle count (review 1) — The reviewer noted the cycle count (1,307,692,307,692) is internally consistent at 34 nodes. Addressed differently: Rather than keeping a potentially stale specific cycle count, the table row was updated to show the formula (base x n / 13) since the node count itself is unverified. This is more accurate than preserving a number that may be wrong if the node count is 31.

3. "Cycle cost formula section is duplicative" — remove/consolidate (review 1) — The reviewer suggested removing the "Cycle costs by subnet type" section since it duplicates the formula already in the properties table and fiduciary section. Skipped: The section was retained but improved (formula generalized, stale fiduciary cost row updated, USD caveat added). It provides a useful at-a-glance cost comparison for application and European subnets that is not present elsewhere on the page. Removing it would reduce reference utility.